%% Read Input Data from CSV Data Files
% by Jaromir Benes
%
% Prepare a three-country database (Australia, Canada, Norway) that will be
% later used to estimate VAR models.

%% Clear Workspace
%
% Clear workspace, close all figure windows, move to the top of the command
% screen, and check the IRIS version.

clear;
close all;
home;
irisrequired 20130401;

%% Data Files
%
% Contained in this tutorial are CSV data files with some basic
% macroeconomic series for three countries, Australia (Au), Canada (Ca),
% and Norway (No):
%
% * `Data_Au.csv`
% * `Data_Ca.csv`
% * `Data_No.csv`
%
% Open, view and edit these data files either in a spreadsheet program
% (which is more comfortable because it preserves the row-columnn
% structure) or in any text editor (which gives a better idea how the files
% are organised inside).

%% Read raw data
%
% There are three CSV data files contained within this tutorial:
% `Data_AU.csv` (Australia), `Data_CA.csv` (Canada), and `Data_NO.csv`
% (Norway), with four time series in each:
%
% * `GDPR`, real GDP index,
% * `I3M`, 90-day money market rate, 
% * `PIXEF`, CPI inflation excluding energy and food,
% * `XUSD`, exchange rate against the USD.
%
% Create a struct `d` with three country sub-databases in it: `d.Au`,
% `d.Ca` and `d.No`. This is how input data are supposed to be organised
% when estimating a panel VAR.
%
% CSV files (CSV stands for Comma Separated Values) are plain text files.
% To see what's inside them, and even to make edits in them, use any kind
% of text editor (including the Matlab editro) or spreadsheet program.

d = struct();

d.Au = dbload('Data_Au.csv', ...
    'skipRows=',1:3, ...
    'userDataFieldList=',5:8, ...
    'commentRow=','Detailed_Descriptor', ...
    'nan=','n.a.');

d.Ca = dbload('Data_Ca.csv', ...
    'skipRows=',1:3, ...
    'userDataFieldList=',5:8, ...
    'commentRow=','Detailed_Descriptor', ...
    'nan=','n.a.');

d.No = dbload('Data_No.csv', ...
    'skipRows=',1:3, ...
    'userDataFieldList=',5:8, ...
    'commentRow=','Detailed_Descriptor', ...
    'nan=','n.a.');


d %#ok<NOPTS>
d.Au
d.Ca
d.No

%% Seasonally Adjust Selected Time Series 
%
% In each country sub-database, find time series named with an `_U` at the
% end, and run `X12` to seasonally adjust these series. The new, seasonally
% adjusted, series are named the same with the `_U` removed. Note that in
% some country sub-databases, there are no time series to adjust, so no
% `X12` is invoked for them.

d.Au = dbbatch(d.Au,'$1','x12(d.Au.$0)','nameFilter=','(.*)_U');
d.Ca = dbbatch(d.Ca,'$1','x12(d.Ca.$0)','nameFilter=','(.*)_U');
d.No = dbbatch(d.No,'$1','x12(d.No.$0)','nameFilter=','(.*)_U');

d.Au
d.Ca
d.No

%% Transform Input Data
%
% Transform the input series giving them also names used later in the VAR
% models:
%
% * `infl` is (seasonally adjusted) CPI inflation excluding food and
% energy,
% * `gap` is a percent Hodrick-Prescott gap in real GDP,
% * `int` is a 90-day money market rate,
% * `dex` is the percent annualised rate of change in the nominal exchange
% rate (positive sign means depreciation).
%
% * <?hpf2?> The function `hpf2` is identical to `hpf` (see help on this
% function for details) except it swaps the output arugments, i.e. the gap
% comes out first.
%
% * <?apct?> The function `apct` calculates the annualised percent rate of
% change.
%

d.Au.infl = d.Au.PIXEF;
d.Au.gap = hpf2(100*log(d.Au.GDPR)); %?hpf2?
d.Au.int = d.Au.I3M;
d.Au.dex = apct(d.Au.XUSD); %?apct?

d.Ca.infl = d.Ca.PIXEF;
d.Ca.gap = hpf2(100*log(d.Ca.GDPR));
d.Ca.int = d.Ca.I3M;
d.Ca.dex = apct(d.Ca.XUSD);

d.No.infl = d.No.PIXEF;
d.No.gap = hpf2(100*log(d.No.GDPR));
d.No.int = d.No.I3M;
d.No.dex = apct(d.No.XUSD);

d.Au
d.Ca
d.No

%% Plot Series Used Later in Estimating Panel VARs
%
% Use the `&` operator  to combine the three country sub-databases into
% one, where each time series has three columns, and report the four series
% used later in the VAR models.

dbplot(d.Au & d.Ca & d.No,Inf,{ ...
    '"Inflation excl food & energy, % Q/Q annualised" infl', ...
    '"Real GDP gap, %" gap', ...
    '"3-month interest rate, % PA" int', ...
    '"Exchange rate depreciation, National/USD, % Q/Q annualised" dex'}, ...
    'tight=',true,'zeroline=',true);

grfun.bottomlegend('Australia','Canada','Norway');

%% Save Data for Future Use
%
% Save the struct `d` with the country sub-databases to a binary file named
% `read_data.mat` for future use.

save read_data.mat d;

%% Help on IRIS Functions Used in This M-file
%
% Use either `help` to display help in the command window, or `idoc`
% to display help in an HTML browser window.
%
%    help dbase/dbload
%    help dbase/dbbatch
%    help dbase/dbplot
%    help tseries/hpf2
%    help tseries/apct
%    help grfun/bottomlegend
